<!-- ##### SECTION Title ##### -->
-creating
+Creating a Pixbuf from Data in Memory
<!-- ##### SECTION Short_Description ##### -->
-
+Creating a pixbuf from image data that is already in memory.
<!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
+ <para>
+ </para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
-
<!-- ##### FUNCTION gdk_pixbuf_new_from_art_pixbuf ##### -->
<para>
@data:
@Returns:
-
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
<!-- ##### SECTION Title ##### -->
-file-loading
+File Loading
<!-- ##### SECTION Short_Description ##### -->
-
+Loading a pixbuf from a file.
<!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
-
+ <para>
+ The GdkPixbuf library provides a simple mechanism for loading an
+ image from a file in synchronous fashion. This means that the
+ library takes control of the application while the file is being
+ loaded; from the user's point of view, the application will block
+ until the image is done loading.
+ </para>
+
+ <para>
+ This interface can be used by applications in which blocking is
+ acceptable while an image is being loaded. It can also be used to
+ load small images in general. Applications that need progressive
+ loading can use the #GdkPixbufLoader functionality instead.
+ </para>
<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
+ <para>
+ #GdkPixbufLoader
+ </para>
<!-- ##### FUNCTION gdk_pixbuf_new_from_file ##### -->
<para>
@filename:
@Returns:
-
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
</para>
-
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
-
<!-- ##### USER_FUNCTION ModulePreparedNotifyFunc ##### -->
<para>
</para>
-
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
-
<!-- ##### MACRO GDK_PIXBUF_LOADER ##### -->
<para>
<!-- ##### SECTION Title ##### -->
-gdk-pixbuf
+The GdkPixbuf Structure
<!-- ##### SECTION Short_Description ##### -->
-
+Information that describes an image.
<!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
+ <para>
+ The <structname>GdkPixbuf</structname> structure contains
+ information that describes an image in memory. It is actually a
+ simple wrapper that adds reference counting capabilities to an
+ #ArtPixBuf structure.
+ </para>
<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
+ <para>
+ #ArtPixBuf
+ </para>
<!-- ##### STRUCT GdkPixbuf ##### -->
-<para>
+ <para>
+ This is the main structure in the GdkPixbuf library. This
+ structure adds reference counting capabilities to an #ArtPixBuf
+ structure.
+ </para>
-</para>
-
-@ref_count:
-@art_pixbuf:
+@ref_count: Reference count.
+@art_pixbuf: An #ArtPixBuf that actually contains the description of
+the image data.
<!-- ##### FUNCTION gdk_pixbuf_get_format ##### -->
<para>
</para>
-@pixbuf:
-@Returns:
+@pixbuf:
+@Returns:
<!-- ##### FUNCTION gdk_pixbuf_get_n_channels ##### -->
</para>
-@pixbuf:
-@Returns:
+@pixbuf:
+@Returns:
<!-- ##### FUNCTION gdk_pixbuf_get_has_alpha ##### -->
</para>
-@pixbuf:
-@Returns:
+@pixbuf:
+@Returns:
<!-- ##### FUNCTION gdk_pixbuf_get_bits_per_sample ##### -->
</para>
-@pixbuf:
-@Returns:
+@pixbuf:
+@Returns:
<!-- ##### FUNCTION gdk_pixbuf_get_pixels ##### -->
</para>
-@pixbuf:
-@Returns:
+@pixbuf:
+@Returns:
<!-- ##### FUNCTION gdk_pixbuf_get_width ##### -->
</para>
-@pixbuf:
-@Returns:
+@pixbuf:
+@Returns:
<!-- ##### FUNCTION gdk_pixbuf_get_height ##### -->
</para>
-@pixbuf:
-@Returns:
+@pixbuf:
+@Returns:
<!-- ##### FUNCTION gdk_pixbuf_get_rowstride ##### -->
</para>
-@pixbuf:
-@Returns:
-
+@pixbuf:
+@Returns:
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
</para>
-
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
-
<!-- ##### MACRO GNOME_CANVAS_PIXBUF ##### -->
<para>
<!-- ##### SECTION Title ##### -->
-refcounting
+Reference Counting
<!-- ##### SECTION Short_Description ##### -->
-
+Functions to perform reference counting on a #GdkPixbuf.
<!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
-
+ <para>
+ #GdkPixbuf structures are reference counted. This means that
+ an application can share a single pixbuf among many parts of the
+ code. When a piece of the program needs to keep a pointer to a
+ pixbuf, it should add a reference to it. When it no longer needs
+ the pixbuf, it should subtract a reference. The pixbuf will be
+ destroyed when its reference count drops to zero. Newly-created
+ #GdkPixbuf structures start with a reference count of one.
+ </para>
<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
+ #GdkPixbuf
+ #ArtPixBuf
+ </para>
<!-- ##### FUNCTION gdk_pixbuf_ref ##### -->
-<para>
-</para>
+ </para>
@pixbuf:
@pixbuf:
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
</para>
-
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
-
<!-- ##### ENUM GdkPixbufAlphaMode ##### -->
<para>
1999-11-04 Federico Mena Quintero <federico@redhat.com>
+ * doc/tmpl/gdk-pixbuf.sgml: Populated.
+
+ * doc/tmpl/refcounting.sgml: Populated.
+
+ * doc/tmpl/file-loading.sgml: Populated.
+
+ * src/gdk-pixbuf.c: Added documentation comments.
+
+ * src/gdk-pixbuf-io.c (gdk_pixbuf_new_from_file): Added
+ documentation comments.
+
* doc/: Finished integrating the documentation framework.
1999-11-03 Federico Mena Quintero <federico@redhat.com>
return NULL;
}
+/**
+ * gdk_pixbuf_new_from_file:
+ * @filename: Name of file to load.
+ *
+ * Creates a new pixbuf by loading an image from a file. The file format is
+ * detected automatically.
+ *
+ * Return value: A newly-created pixbuf, or NULL if any of several error
+ * conditions occurred: the file could not be opened, there was no loader for
+ * the file's format, there was not enough memory to allocate the image buffer,
+ * or the image file contained invalid data.
+ **/
GdkPixbuf *
gdk_pixbuf_new_from_file (const char *filename)
{
free (data);
}
+\f
+
+/* Create an empty pixbuf */
+
/**
* gdk_pixbuf_new:
* @format: Image format.
* @bits_per_sample: Number of bits per color sample.
* @width: Width of image in pixels.
* @height: Height of image in pixels.
- *
+ *
* Creates a new &GdkPixbuf structure and allocates a buffer for it. The buffer
* has an optimal rowstride. Note that the buffer is not cleared; you will have
* to fill it completely.
- *
+ *
* Return value: A newly-created &GdkPixbuf, or NULL if not enough memory
* could be allocated for the image buffer.
**/
free_buffer, NULL);
}
+\f
/* Convenience functions */
+
+/**
+ * gdk_pixbuf_get_format:
+ * @pixbuf: A pixbuf.
+ *
+ * Queries the image format (color model) of a pixbuf.
+ *
+ * Return value: Image format.
+ **/
ArtPixFormat
gdk_pixbuf_get_format (GdkPixbuf *pixbuf)
{
return (pixbuf->art_pixbuf->format);
}
+/**
+ * gdk_pixbuf_get_n_channels:
+ * @pixbuf: A pixbuf.
+ *
+ * Queries the number of channels of a pixbuf.
+ *
+ * Return value: Number of channels.
+ **/
int
gdk_pixbuf_get_n_channels (GdkPixbuf *pixbuf)
{
return (pixbuf->art_pixbuf->n_channels);
}
+/**
+ * gdk_pixbuf_get_has_alpha:
+ * @pixbuf: A pixbuf.
+ *
+ * Queries whether a pixbuf has an alpha channel (opacity information).
+ *
+ * Return value: TRUE if it has an alpha channel, FALSE otherwise.
+ **/
int
gdk_pixbuf_get_has_alpha (GdkPixbuf *pixbuf)
{
return (pixbuf->art_pixbuf->has_alpha);
}
+/**
+ * gdk_pixbuf_get_bits_per_sample:
+ * @pixbuf: A pixbuf.
+ *
+ * Queries the number of bits per color sample in a pixbuf.
+ *
+ * Return value: Number of bits per color sample.
+ **/
int
gdk_pixbuf_get_bits_per_sample (GdkPixbuf *pixbuf)
{
return (pixbuf->art_pixbuf->bits_per_sample);
}
+/**
+ * gdk_pixbuf_get_pixels:
+ * @pixbuf: A pixbuf.
+ *
+ * Queries a pointer to the pixel data of a pixbuf.
+ *
+ * Return value: A pointer to the pixbuf's pixel data.
+ **/
guchar *
gdk_pixbuf_get_pixels (GdkPixbuf *pixbuf)
{
return (pixbuf->art_pixbuf->pixels);
}
+/**
+ * gdk_pixbuf_get_width:
+ * @pixbuf: A pixbuf.
+ *
+ * Queries the width of a pixbuf.
+ *
+ * Return value: Width in pixels.
+ **/
int
gdk_pixbuf_get_width (GdkPixbuf *pixbuf)
{
return (pixbuf->art_pixbuf->width);
}
+/**
+ * gdk_pixbuf_get_height:
+ * @pixbuf: A pixbuf.
+ *
+ * Queries the height of a pixbuf.
+ *
+ * Return value: Height in pixels.
+ **/
int
gdk_pixbuf_get_height (GdkPixbuf *pixbuf)
{
return (pixbuf->art_pixbuf->height);
}
+/**
+ * gdk_pixbuf_get_rowstride:
+ * @pixbuf: A pixbuf.
+ *
+ * Queries the rowstride of a pixbuf, or the number of bytes between rows.
+ *
+ * Return value: Number of bytes between rows.
+ **/
int
gdk_pixbuf_get_rowstride (GdkPixbuf *pixbuf)
{
projects / gtk4.git / commitdiff